<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">











<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Java Guardian Content API - Java Guardian Content API - Overview</title>
    <style type="text/css" media="all">
      @import url("./css/maven-base.css");
      @import url("./css/maven-theme.css");
      @import url("./css/site.css");
    </style>
    <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
          <meta name="author" content="Michael Lee" />
        <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
      </head>
  <body class="composite">
    <div id="banner">
                    <span id="bannerLeft">
    
            Guardian :: API :: Library
    
            </span>
                    <div class="clear">
        <hr/>
      </div>
    </div>
    <div id="breadcrumbs">
          
  

  
    
  
  
    
              <div class="xright">      
  

  
    
  
  
    
  </div>
      <div class="clear">
        <hr/>
      </div>
    </div>
    <div id="leftColumn">
      <div id="navcolumn">
           
  

  
    
  
  
    
                   <h5>Java Guardian Content API</h5>
            <ul>
              
    <li class="none">
              <strong>Overview</strong>
        </li>
              
    <li class="none">
                    <a href="usage.html">Usage</a>
          </li>
              
    <li class="none">
                    <a href="examples.html">Examples</a>
          </li>
          </ul>
              <h5>Project Documentation</h5>
            <ul>
              
                
              
      
            
      
            
      
            
      
            
      
            
      
            
      
            
      
            
      
            
      
              
        <li class="collapsed">
                    <a href="project-info.html">Project Information</a>
                </li>
              
                
              
      
            
      
              
        <li class="collapsed">
                    <a href="project-reports.html">Project Reports</a>
                </li>
          </ul>
                                           <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
            <img alt="Built by Maven" src="./images/logos/maven-feather.png"></img>
          </a>
                       
  

  
    
  
  
    
            <div id="lastPublished">
        Last Published: 03-09-09
              </div>
            </div>
    </div>
    <div id="bodyColumn">
      <div id="contentBox">
        <div class="section"><h2>This document provides a simple overview of the Java client for the Guardian Content API</h2>
</div>
<div class="section"><h2>Overview</h2>
<p>This client is a wrap around the Guardian REST style content API. The Java client implements a simple facade to make it as easy as possible to access The Guardian content - and behind the scenes it implements an OO wrap around the API, with support for HTTP access, XML/Object deserialization, caching, and Spring support.</p>
<p>A key feature of the Java client is that it is very flexible, allowing you to use all of the advanced features (pooled HTTP connections, configurable caching, XML unmarshalling) or none of them - the choice is yours.</p>
</div>
<div class="section"><h2>HTTP Clients</h2>
<p>The Java client needs to make use of an HTTP client to make requests to the Guardian API. By default, the client will make use of the Apache Commons HTTP Client, and configure it with sensible defaults (will timout the connection after 60 seconds and will time out waiting for a response after 60 seconds). The HTTP client has the advantage that it has built in support for managing / re-using a pool of threadsafe HTTP Connections to try and speed up content requests.</p>
<p>To explicitly configure the httpClient you can reference the spring reference files in docs/spring The Apache Commons HTTP client can be exlicitly used during normal construction using code such as the following</p>
<div class="source"><pre>  GuardianHttpClient httpClient = new CommonsHttpClient();
  GuardianContentSerializer contentSerializer = new JaxbContentSerializer();
  String apiKey = &quot;&lt;your API key&gt;&quot;;
  SimpleGuardianContentClient contentClient = new SimpleGuardianContentClientImpl(httpClient,contentSerializer,apiKey); </pre>
</div>
<p>At a Spring level this requires the definition of the bean with a reference such as the following</p>
<div class="source"><pre>        &lt;bean id=&quot;myCommonsHttpClient&quot; class=&quot;com.guardianapis.api.http.CommonsHttpClient&quot;/&gt;

        &lt;bean id=&quot;guardianContentClientBase&quot; class=&quot;com.guardianapis.api.client.SimpleGuardianContentClientImpl&quot;&gt;
                &lt;constructor-arg index=&quot;0&quot; ref=&quot;myCommonsHttpClient&quot;/&gt;                  &lt;!-- GuardianHttpClient implementation --&gt;
                &lt;constructor-arg index=&quot;1&quot; ref=&quot;guardianJaxbSerializer&quot;/&gt;                               &lt;!-- GuardianContentSerializer implementation --&gt;
                &lt;constructor-arg index=&quot;2&quot; value=&quot;&lt;your API key&gt;&quot;/&gt;     &lt;!-- API Key --&gt;
        &lt;/bean&gt;</pre>
</div>
<p>If you do not wish to use the Apache HTTP Client, then you can configure a simple HTTP client that only makes use of the standard Java classes for network connectivity using the following Java code.</p>
<div class="source"><pre>  GuardianHttpClient httpClient = new SimpleHttpClient();
  GuardianContentSerializer contentSerializer = new JaxbContentSerializer();
  String apiKey = &quot;&lt;your API key&gt;&quot;;
  SimpleGuardianContentClient contentClient = new SimpleGuardianContentClientImpl(httpClient,contentSerializer,apiKey); </pre>
</div>
<p>And this would use the following at the Spring level</p>
<div class="source"><pre>        &lt;bean id=&quot;mySimpleHttpClient&quot; class=&quot;com.guardianapis.api.http.SimpleHttpClient&quot;/&gt;

        &lt;bean id=&quot;guardianContentClientBase&quot; class=&quot;com.guardianapis.api.client.SimpleGuardianContentClientImpl&quot;&gt;
                &lt;constructor-arg index=&quot;0&quot; ref=&quot;mySimpleHttpClient&quot;/&gt;                   &lt;!-- GuardianHttpClient implementation --&gt;
                &lt;constructor-arg index=&quot;1&quot; ref=&quot;guardianJaxbSerializer&quot;/&gt;                               &lt;!-- GuardianContentSerializer implementation --&gt;
                &lt;constructor-arg index=&quot;2&quot; value=&quot;&lt;your API key&gt;&quot;/&gt;     &lt;!-- API Key --&gt;
        &lt;/bean&gt;</pre>
</div>
</div>
<div class="section"><h2>XML/Java Conversion</h2>
<p>The Java client includes three different means for converting between the raw XML returned by the Guardian Content API and Java objects.</p>
<p>The default approach uses the standard JAXB2 approach - and this is implemented by default when using the SimpleGuardianContentClient (either using Spring or normal Java constructors). The domain objects in com.guardianapis.api.domain.jaxb were generated using the reference implementation JAXB binding compiler (using the XJC Maven plugin) - and these are the objects that will be returned by the three API calls on the SimpleGuardianContentClient interface, e.g. the SimpleGuardianContentClient.search(...) method return com.guardianapis.api.domain.jaxb.Search etc.</p>
<p>The second approach uses the same set of domain objects, but this time uses the Thoughtworks XStream serialization/deserialization engine. Although not performance tested as part of the client API, XStream is promoted as being a fast, easy means for XML/Java translation, and has been included for users who already use XStream.</p>
<p>The third approach uses the Apache XMLBeans library to provide a Java representation of the underlying XML. The advantage of the XMLBeans library is that the Java objects that are returned are essentially interchangeable with XML, and XMLBeans provides easy means of accessing/filtering parts of the Java/XML response using XPath.</p>
<p>Finally, if you want to keep the advantages of the OO Java Client approach with the built in HTTP support, but want to manage your own XML/Java conversion (or use the raw XML) you can use the basic operations provided on the GuardianContentClient interface, and implemented in the BaseGuardianContentClient</p>
</div>
<div class="section"><h2>Caching</h2>
<p>An extra feature provided by the Spring client is the use of AOP to inject/intercept caching functionality into the Java client. This is enabled simply by adding a reference to the guardian-content-client-caching.xml Spring configuration file (see the Spring readme.txt document in doc/spring).</p>
<p>The Spring caching configuration makes use of a library written by Pieter Coucke and made available at http://opensource.atlassian.com/confluence/spring/display/DISC/AOP+Cache. This library allows for various underling cache providers (including OSCache, EHCache, Swarmcache, and a simple MemoryCacheInterceptor) to be plugged in to provide caching for the Java client.</p>
<p>If you wish to disable this caching layer, simply avoid referencing the guardian-content-client-caching.xml file in your Spring application context.</p>
</div>
<div class="section"><h2>Examples</h2>
<p>See the examples documentation more details on a related project which is included in the examples sub-directory.</p>
</div>
<div class="section"><h2>Usage</h2>
<p>Some more detail on including the Java Guardian Content API in your own project is included in the usage documentation. </p>
</div>

      </div>
    </div>
    <div class="clear">
      <hr/>
    </div>
    <div id="footer">
      <div class="xright">&#169;  
          2009
    
          
  

  
    
  
  
    
   - <a href="http://maven.apache.org/privacy-policy.html">Privacy Policy</a></div>
      <div class="clear">
        <hr/>
      </div>
    </div>
  </body>
</html>
